home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 038a / libwiz12.zip / LIBWIZ.DOC < prev    next >
Text File  |  1991-12-05  |  15KB  |  314 lines
  1.                  The Library Wizard's *BASIC Library Manager*           page 1
  2.                  =------------------------------------------=
  3.                                   Version 1.2
  4.  
  5.                LIBWIZ  Copyright (c) 1991  Thomas G. Hanlin III
  6.  
  7.  
  8.  
  9. This is LIBWIZ, a collection of utilities for managing BASIC libraries.  It
  10. allows you to customize your libraries, selecting just the routines you want.
  11. As well as creating a new library, LIBWIZ creates a corresponding "include"
  12. file and a quick reference of the routines in the library.
  13.  
  14. LIBWIZ requires a special description file to work with a library.  My own
  15. libraries come complete with description files (BASWIZ as of v1.5, PBClone as
  16. of v1.4).  The LIBWIZU utility assists in creating description files for
  17. libraries which don't have them.  The UNLIB utility allows you to extract all
  18. .OBJ files from a .LIB, since LIBWIZ needs to work with the .OBJs directly.
  19.  
  20. The LIBWIZ collection is copyrighted and may be distributed only under the
  21. following conditions:
  22.  
  23.    1) No fee of over $10.00 may be charged for distribution.  This
  24.       restriction applies only to physical copies and is not meant to
  25.       prevent distribution by telecommunication services.
  26.  
  27.    2) All LIBWIZ files must be distributed together in original, unaltered
  28.       form.  This includes CATALOG.TXT, FILES.LST, LIBWIZ.DOC, LIBWIZ.EXE,
  29.       LIBWIZ.NEW, LIBWIZU.EXE, LIB2OBJ.BAT, REGISTER.TXT, UNLIB.EXE, and
  30.       WHERE.BBS.
  31.  
  32. You use these utilities at your own risk.  They have been tested by me on my
  33. own computer, but I will not assume any responsibility for any problems which
  34. they may cause you.  If you do encounter a problem, please let me know about
  35. it, and I will do my best to verify and repair the error.
  36.  
  37.                               Table of Contents                         page 2
  38.  
  39.  
  40.  
  41.  Overview and Legal Info ................................................ 1
  42.  
  43.  The LIBWIZ Library Manager ............................................. 3
  44.  
  45.  The LIBWIZU .INF Maker ................................................. 5
  46.  
  47.  Merging Libraries ...................................................... 6
  48.  
  49.  Portability Notes ...................................................... 7
  50.  
  51.  Miscellaneous .......................................................... 8
  52.  
  53.                           The LIBWIZ Library Manager                    page 3
  54.  
  55.  
  56.  
  57. A library is a collection of routines, or partial programs, which can be used
  58. directly as if they were part of the language itself.  A library may be
  59. considered as a language extender.  Since library routines can be written in
  60. a variety of languages, they may provide capabilities that are impossible
  61. using the target language alone.  Even if the routines do something that is
  62. within the capabilities of the target language, they are valuable in that
  63. they are already tested and provide a standardized approach to whatever they
  64. do.  The flexibility of libraries is a part of their power... and a problem!
  65.  
  66. The sheer number and variety of libraries available for BASIC is staggering.
  67. Many libraries contain hundreds of different routines of all descriptions!
  68. Sifting out just the routines you need is a hassle.  It's rarely practical to
  69. combine entire libraries, either due the presence of routines by the same
  70. name in different libraries or simply memory limitations.  In fact, my
  71. shareware libraries BASWIZ and PBClone have each grown too large for BASIC to
  72. deal with comfortably!
  73.  
  74. LIBWIZ provides a solution.  It allows you to choose just the routines you
  75. want from a library, either individually or by category.  It resolves any
  76. interdependencies to make sure the library contains all the routines it needs
  77. to function.  As well as customizing the library itself, LIBWIZ creates new
  78. "quick reference" and "include" files.
  79.  
  80. In order to do its stuff, LIBWIZ needs a ".INF" file which tells it about the
  81. library to be customized.  Appropriate files are included with the current
  82. versions of my own libraries.  The LIBWIZU utility can be used to create .INF
  83. files for other libraries.  Aside from the .INF file, LIBWIZ needs to have
  84. access to all of the .OBJ files that make up the library.  If your library
  85. didn't come with the separate .OBJ files, you can usually extract them from
  86. the .LIB using UNLIB.EXE and LIB2OBJ.BAT:
  87.  
  88.    UNLIB LibName
  89.    LIB2OBJ
  90.  
  91. Note that I said "usually"!  On occasion, LIB refuses to recognize an object
  92. name that UNLIB specifies.  I've inspected the library in these cases and the
  93. object name appears correct.  I'm not sure why LIB doesn't cooperate.  The
  94. problem is uncommon, however, and you'll probably never run across it.
  95.  
  96.                           The LIBWIZ Library Manager                    page 4
  97.  
  98.  
  99.  
  100. To use LIBWIZ, move to the directory which holds the .OBJ files and the .INF
  101. file for the library you wish to customize.  The syntax is:
  102.  
  103.    LIBWIZ InfName LibName
  104.  
  105. ...where "InfName" is the name of the .INF file and "LibName" is the name of
  106. the desired .LIB library.  The option "/B" can be used to force a monochrome
  107. display, although LIBWIZ will usually detect mono displays by itself.  I
  108. don't -think- any further instructions are needed, as picking the routines is
  109. a fairly simple process-- give it a go. If I've blundered in this regard,
  110. please let me know, and I'll try to provide more detailed instructions!
  111.  
  112. When you are done, provided that you told LIBWIZ to go ahead and create a
  113. library, it will create a number of files: an "include" (.BI) file, a revised
  114. library info (.INF) file, a batch file (.BAT) and response file (.IN) to
  115. actually make the library, and a quick reference (.REF) file.  These files
  116. will all take the name you specified as "LibName".
  117.  
  118. LIBWIZ doesn't actually create a library itself, as mentioned above.  It
  119. makes a batch file which tells LIB.EXE to create the desired library.  Only
  120. the .LIB form of the library will be created.  This is the form of library
  121. used when compiling from the command line or compiling to an .EXE from inside
  122. the QuickBASIC environment.  If you expect to use the library inside the
  123. QuickBASIC environment, you will need to make one in .QLB form as well.  This
  124. can be done by typing something like the following:
  125.  
  126.    LINK Libname.LIB/Q/SE:512,,NUL,BQLB45;
  127.  
  128. The "BQLB45" part is only for QuickBASIC 4.5.  For QuickBASIC 4.0, you would
  129. use either "BQLB40" or "BQLB41", depending on the particular QuickBASIC
  130. revision-- use "DIR BQLB*" wherever your QuickBASIC libraries are kept to
  131. find out which.  The BQLBxx.LIB file is provided with QuickBASIC.
  132.  
  133. If you are using the BASCOM "Professional Development System" v7.x, specify
  134. "QBXQLB" instead of BQLBxx.
  135.  
  136.  
  137.  
  138. At the moment, LIBWIZ can handle up to 1,023 routines per library; up to 4
  139. categories per routine; up to 255 categories total.
  140.  
  141. If you are processing a large library, have patience!  LIBWIZ has a lot of
  142. work to do and may take a while to write all the files for a big library.
  143. I'll improve its efficiency further in later versions.
  144.  
  145.                         The LIBWIZU .INF Maker                          page 5
  146.  
  147.  
  148.  
  149. The LIBWIZ library manager requires an .INF file to tell it about a library.
  150. This file specifies routine names, categories, object modules, declarations
  151. and descriptions.  If you don't have an .INF file for your library, the
  152. LIBWIZU utility will handle most of the work of creating it for you.
  153.  
  154. To use LIBWIZU, move to the directory which holds the .OBJ files and .BI
  155. (declaration) file for your library.  Type:
  156.  
  157.    LIBWIZU LibName
  158.  
  159. ...where LibName is the name of the .BI file.  After chugging through the
  160. declaration and object files, LIBWIZU will create an .INF file for the
  161. library.  It will also report on Public routines (routines listed in the
  162. declaration file, which are evidently intended for public use), Private
  163. routines (routines which can be accessed but are not in the declaration file
  164. and are assumed to be private for use by the public routines), and Orphans.
  165. Private routines will not be shown by LIBWIZ, but will be pulled into a
  166. library if needed by a public routine that was selected. Orphans are routines
  167. which are listed in the declaration file but which do not appear in the
  168. object files.  If there are any orphans, ORPHAN.LST will contain their names.
  169.  
  170. The .INF file created by LIBWIZU is not complete.  You must fill it in using
  171. a text editor.  A description for each routine is a good idea, though not
  172. strictly mandatory.  A description may be no longer than 70 characters.  Each
  173. routine must be in at least one category or it is assumed to be private.  A
  174. category can be as many as 16 characters.  A routine may be in up to four
  175. categories (list them on the same line, separated by spaces).
  176.  
  177. Here's a sample entry for a routine (taken from PBCLONE.INF):
  178.  
  179. Name: CLOCK
  180. Mod : CLOCK.OBJ
  181. Decl: DECLARE SUB Clock (BYVAL DisplayOn%)
  182. Type: Display Time
  183. Desc: Keep a clock displayed on the screen
  184.  
  185. The entries are created in this order by default, but may be in any order as
  186. long as the "Name:" definition is first.  If you would like to enter comments
  187. into the file, use "Note:".  Such notes will be ignored by LIBWIZ.
  188.  
  189. If you need information in the .BI file other than just DECLAREs, such as
  190. perhaps TYPE definitions, DEFINT or other statements, you must create an
  191. additional file with an .HDR (header) extension.  If LIBWIZ detects the file
  192. InfName.HDR, it will copy that file to LibName.HDR and "REM $INCLUDE" it in
  193. LibName.BI before the DECLAREs for the library.
  194.  
  195.                                Merging Libraries                        page 6
  196.  
  197.  
  198.  
  199. In order to combine two libraries, you must have both libraries in .LIB form.
  200. A new, combined .LIB can be created with the LIB.EXE utility that comes with
  201. BASIC:
  202.  
  203.    LIB NewLib,+LibOne.LIB+LibTwo.LIB;
  204.  
  205. A combined .QLB can be created using LINK:
  206.  
  207.    LINK LibOne.LIB+LibTwo.LIB/Q/SE:512,NewLib.QLB,NUL,BQLB45;
  208.  
  209. As noted earlier, you may need to use a different name than "BQLB45".  If you
  210. have QuickBASIC 4.0, it will be either "BQLB40" or "BQLB41".  If you have
  211. BASCOM 7.x ("Professional Development System"), it will be "QBXQLB".
  212.  
  213. The /SE option is used to tell LINK it may have to deal with a lot more
  214. routines than it expected by default.  If you get an overflow error, there
  215. are too many routines than will fit into the .QLB library.  Take some out.
  216.  
  217. If both libraries have a routine by the same name, there will be a conflict.
  218. You can fix this by changing the name of the routine in one of the libraries.
  219. My OBJTOOL utility (available elsewhere) allows you to do this.
  220.  
  221. OBJTOOL, like LIBWIZ and LIBWIZU, expects to deal with .OBJ files rather than
  222. with .LIB or .QLB files.  If you only have a .QLB library, there's nothing
  223. you can do about this.  If you have a .LIB library, however, you can use the
  224. LIB.EXE utility to remove .OBJ files from the library.
  225.  
  226. When LIB gives you the "Operations" prompt, use:
  227.  
  228.    *ObjName     to copy an .OBJ file from the library onto your disk
  229.    -ObjName     to delete an .OBJ from the library
  230.    +ObjName     to add an .OBJ to the library
  231.    -+ObjName    to update an .OBJ file in the library from your disk
  232.  
  233. If you don't know the names of the .OBJ modules, ask LIB.  Just press <enter>
  234. when it asks for Operations, then give it the name of a file when it prompts
  235. for a "List file".  The resulting file will contain a list of the modules in
  236. the library and what routines are in each module.
  237.  
  238. When combining libraries, don't forget to combine their .INF files as well!
  239. It takes no more than joining the two files:
  240.  
  241.    COPY LibOne.INF+LibTwo.INF NewLib.INF
  242.  
  243. You can join the .REF and .BI files the same way, or use LIBWIZ to generate
  244. new .REF and .BI files from the new .INF file.
  245.  
  246.                                Portability Notes                        page 7
  247.  
  248.  
  249.  
  250. Routines for BASIC compilers come in assorted variations.  The main category
  251. is the language used to write the routine: BASIC, assembly, or other (C,
  252. Pascal, Fortran).  Each of these is portable to a different degree.
  253.  
  254. Routines written in BASIC will only work with the version of the compiler
  255. they were compiled under.  If the routine was compiled with QB 4.5, it will
  256. only work with programs that are also compiled with QB 4.5.
  257.  
  258. Routines written in C, Pascal, or Fortran are compatible with QuickBASIC 4.0
  259. to 4.5 and BASCOM 6.0 to 7.1.
  260.  
  261. Routines written in assembly language are portable to varying extents.  Older
  262. routines are likely to be compatible only with QB 1.0 to 3.0 and BASCOM
  263. versions before 6.0.  More recent routines are likely to be compatible with
  264. QB 4.0 - 4.5 and BASCOM 6.0 - 7.1; in this case, they may or may not be
  265. compatible with older versions of these compilers, depending on the whim of
  266. the programmer.  The third level of compatibility includes BASCOM 7.0 - 7.1
  267. and QBX: far string compatibility.  This is not yet particularly common.
  268.  
  269. It is possible to write assembly language routines that will work with all
  270. Microsoft-compatible BASIC compilers, from QB 1.0 - QB 4.5, IBM BASCOM 1.0 -
  271. 2.0, MS BASCOM 5.35 - 7.1, and QBX.  However, this is only possible if new
  272. features (like FUNCTIONs and LONG integers) are ignored.
  273.  
  274. The routines in my BASWIZ and PBClone libraries, at least at the time I write
  275. this, are designed with the middle level of compatibility.  The assembly
  276. language routines will work with QB 4.0 - 4.5 and BASCOM 6.0 - 7.1, but not
  277. with QBX (or BASCOM 7.0 - 7.1 with far strings turned on).  The routines in
  278. BASIC are compiled with QuickBASIC 4.5.  The registered versions of the
  279. libraries come with source code, allowing you to compile the .BAS files with
  280. your own compiler.  This extends the range of the BASIC routines to the same
  281. level as the assembly routines.
  282.  
  283.                                  Miscellaneous                          page 8
  284.  
  285.  
  286.  
  287. Note that LIBWIZ places certain limitations on the valid routine names in
  288. order to make it possible to screen out names that are in BASIC's runtime
  289. libraries.  Names may not contain dollar signs, start with underscores, end
  290. with "QQ", or contain lowercase letters.  It is important to understand that
  291. BASIC normally converts routine names to uppercase and removes any type
  292. specifiers from function names, so BASIC is not normally capable of
  293. generating routine names that would break these restrictions (except for
  294. routines ending in QQ, of course).  This is more of a caution for routines
  295. that may have been written in other languages, such as assembly or C.
  296.  
  297. The LIBWIZ utilities were written using QuickBASIC 4.5 and routines from my
  298. BASWIZ and PBClone libraries.  They were linked with Crescent's PDQ library,
  299. which made the .EXE files much smaller.
  300.  
  301. This initial version of LIBWIZ is somewhat rudimentary.  The interface will
  302. improve in later versions.  I also have additional functions and utilities
  303. planned.  Of course, I will be delighted to hear your ideas on how to make
  304. LIBWIZ better.  Let me hear from you!
  305.  
  306. Sampler disks are available from me for $5.00.  These disks contain the
  307. latest versions of many of my shareware and free works, including BASWIZ,
  308. LIBWIZ, OBJTOOL and PBClone.  Please specify disk size.
  309.  
  310.    Thomas G. Hanlin III
  311.    3544 E. Southern Ave. #104
  312.    Mesa, AZ 85204
  313.  
  314.